GSPBabel Documentation

Revision History
Revision 1.0	2005-10-26T10:33:03.0Z	Dave Pawson
Initial conversion from plain text file at gpsbabel.org/readme.html +
Revision 1.1	2005-10-27T07:39:32.0Z	DaveP
Update to cvs, rev 1.143 +
Revision 1.2	2005-10-27T15:25:55.0Z	DaveP
Update to Add toc for formats & brief format description +
Revision 1.3	2005-10-28T15:19:02.0Z	DaveP
Amended structure.

List of Examples

3.1. An example with all options
3.2. Example Usage:
4.1. An example
4.2. For example:
4.3. For example:

Introduction

Table of Contents

THE PROBLEM
THE SOLUTION

THE PROBLEM

There are simply too many gratuitously different file formats +to hold waypoint, track, and route information in various programs +used by computers. GPX (http://www.topografix.com/gpx.asp) defines a +standard in XML to contain all the data, but there are too many +programs that don't understand it yet and too much data that are in an +alternate formats. +

THE SOLUTION

I needed to convert waypoints between a couple of formats, so I +whipped up a converter and based it on an extensible foundation so +that it was easy to add new formats. Most file formats added so far +have taken under 200 lines of reasonable ISO C so they can be stamped +out pretty trivially. Formats that are ASCII text delimited in some +fixed way can be added with no programming at all via our 'style' +mechanism. +

ChapterÂ 1.Â GETTING IT and BUILDING IT

GPSBabel is distributed in source format that will work on +about any operating system and as ready-to-run binaries for some +operating systems, notably Windows. See the "OS-Specific notes" at +gpsbabel.orgfor +instructions on those binary kits. +

For operating systems where no binary is provided, you will +have to build it. The code should be compilable on any system with +ISO C89 compilers. It's been tested on UnixWare, OpenServer, OS/X, +Linux, Solaris, and a variety of processors and compilers. +

Libexpat is required for source builds. If you get errors +about expat.h being missing, you must either edit the Makefile to tell +the compiler where it is or install it in a sensible place. Exapt can +be downloaded from http://expat.sourceforge.net and is part of Apache +so it's very portable. +

ChapterÂ 2.Â USAGE

Table of Contents

Invocation
ADVANCED USAGE
ROUTE AND TRACK MODES

Invocation

Invocation was meant to be flexible. Unfortunately, + that can sometimes lead to unwieldy command lines.

gpsbabel -?

will always show you the supported file types. To use + this program, just tell it what you're reading, where to read + it from, what you're writing, and what to write it to. For + example:

gpsbabel -i geo -f /tmp/geocaching.loc -o gpx -F /tmp/geocaching.gpx

tells it to read the first file in geocaching.com + format and create a new file in GPX format.

This command will read from a Magellan unit attached + to the first serial port on a Linux system (device names will + vary on other OSes) and write them as a geocaching loc file. + The second command does the same for windows.

gpsbabel -i magellan -f /dev/ttyS0 -o geo -F mag.loc

gpsbabel -i magellan -f com1 -o geo -F mag.loc

Optionally, you may specify "-s" in any command line. This + causes the program to ignore any "short" names that may be + present in the source data format and synthesize one from the + long name. This is particularly useful if you're writing to + a target format that isn't the lowest common denominator but + the source data was written for the lowest common + denominator. I use this for writing data from geocaching.com + to my Magellan so my waypoints have "real" names instead of + the 'GC1234' ones that are optimized for NMEA-only receivers. + A geocacher with a Magellan receiver may thus find commands + like this useful.

 gpsbabel -s -i geo -f geocaching.loc -o magellan -F /dev/ttyS0

 gpsbabel -s -i geo -f geocaching.loc -o magellan -F com1

ADVANCED USAGE

Argument are processed in the order they appear on the command +line and are translated internally into a pipeline that data flows +through when executed. Normally one would:

read from one input

optionally apply filters

write into one output

but GPSBabel is flexible enough to allow more complicated +operations such as reading from several files (potentially of +different types), applying a filter, reading more data, then write the +merged data to multiple destinations. +

The input file type remains unchanged until a new + -i argument is seen. + Files are read in the order they appear. So you could merge + three input files into one output file with:

gpsbabel -i geo -f 1.loc -f 2.loc -f 3.loc -o geo -F big.loc

You can merge files of different types:

gpsbabel  -i geo -f 1.loc -i gpx -f 2.gpx -i pcx 3.pcx \ 
+-o gpsutil -F big.gps

You can write the same data in different output formats:

gpsbabel -i geo -f 1.loc -o gpx -F 1.gpx -o pcx 1.wpt

If you want to change the character set of input or/and + output side you can do this with the option -c + <character set>. You can get a complete list + of supported character sets with "gpsbabel -l". To change + the character set on both sides you should do this:

gpsbabel -i xcsv,style=foo.style -c latin1 -f foo  \
+	         -o xcsv,style=bar.style -c ms-ansi -F bar

Note, that some formats has a fixed character set and ignore this option.

ROUTE AND TRACK MODES

Most formats will make reasonable attempt to work + transparently with waypoints, tracks, and routes. Some + formats, like 'garmin' and 'magellan' require the -t flag to work with tracks and + -r to work with + routes. -w is for + waypoints, and is the default. So if you wanted to read all + data from your unit into a gpx file, you might use a command + like:

 gpsbabel -t -r -w -i magellan -f com1:  -o gpx -F backup.gpx

Tracks and routes are advanced features and don't try + to handle every possible hazard that can be encountered + during a conversion. If you're merging or converting files + of similar limitations, things work very well.

Tracks and routes will sometimes be converted to a + list of waypoints when necessary, f.i. when writing into one + of the CSV formats. The inverse operation is not supported + right now, so reading the converted track back from CSV will + always result in a list of waypoints, not the original track. +

The presence of -s on the command line tends to + creats havoc on tracks and routes since many of these formats + rely on internal linkages between such points and renaming + them may break those linkages. In general, don't use + -s when tracks or + routes are present. +

ChapterÂ 3.Â THE FORMATS

AN1

DeLorme format

This format supports the DeLorme ".an1" drawing file + format. It can currently be used to either read or write + drawing files. If you use this format to create drawing + files with routes or waypoints from another source, it will + currently create "Red Flag" symbols for waypoints, and thick + red lines for routes or tracks. It is possible to merge two + drawing layers by doing something like this: +

gpsbabel -i an1 -f one.an1 -f two.an1 -o an1 -F merged.an1
+

In this case, the merged data will contain all of the + properties of the original data. +

If your original data contains geocaching-specific + information such as difficulty and terrain, GPSBabel will + automatically include that information in the waypoint + descriptions in the generated drawing file. If you do not + want that, specify the "nogc" option on the command + line:

gpsbabel -i gpx -f 12345.gpx -o an1,nogc -F 12345.an1

The "deficon" option allows you to specify which symbol + to use for points that don't have a symbol already. It + defaults to "Red Flag" but it accepts any symbol name you can + put in a DeLorme export file. To find the name of a specific + symbol in Street Atlas, let the mouse pointer hover over it + for a few seconds and the name will be displayed.

The "color" option allows you to specify the color for line + data. It accepts color names of the form "#FF0000" (red) or + any of the 16 common color names from the Cascading Style + Sheets specification.i

The "zoom" option specifies at what zoom level Street + Atlas will begin showing reduced versions of your symbols. + The default is 10. Setting zoom to 0 will disable this + feature. Setting it to anything but the default will + override the zoom level specified on any waypoints that were + read from an existing an1 file; this is by design. +

GPSBabel has limited experimental support for other + types of layers besides the default "drawing" layer with the + use of two options: +

The "type" option specifies the type of the drawing + layer to be created. The supported values are "drawing", + "road", "trail", "waypoint", or "track". If you do not + specify a type, the default will be either the type of the + previous an1 file or "drawing" if there is no previous file. + This lets you merge, for example, two road layers without + having to specify "type=road" for the output.

If you are creating a road layer, you may also use the + "road" option, which allows you to change the types of roads + based on their names. You can change multiple roads at the + same time. Currently supported types are

+ limited Limited-access freeways

+ toll Limited-access toll highways

+ ramp Access ramps for limited-access highways

+ us National highways (e.g. US routes)

+ primary Primary State/Provincial routes

+ state State/Provincial routes

+ major Major Connectors

+ ferry Ferry Routes

+ local Local Roads

+ editable User-drawn Roads +

GPSBabel defaults to creating editable roads. These + are routed just like local roads, but may be edited with the + drawing tools in Street Atlas.

This option has a special format that is best + demonstrated by example:

"road=I-599!limited!Beecher St.!major"

+ This option will cause any road named "I-599" to become a limited- + access highway and any road named "Beecher St." to become a major + connector. Note that roads that have had their types changed in + this way are not editable in Street Atlas, so make sure they are + where you want them before you change them, and make sure to keep + a backup of your original road layer. Note that the ! is a shell + metacharacter in bash and possibly other shells, so you may have to + use single quotes or some other escape mechanism. +

BAROIQ

Brauniger IQ series

Serial download protocol for the Brauniger IQ series of + barograph recording flight instruments. Creates a track of + altitude vs time which can be merged with a GPS track of the + same flight to create a three dimensional IGC file.

BCR

Motorrad Routeplanner 2002 -

This file format (extension .bcr) is used in "Motorrad + Routenplaner 2002-..." by Map&Guide. It is a + route-onle format. If you own a newer release (2005...) you + can also use the XML export and convert via gpsbabel ... -i tef ... to your + preferred format. May be there are other products from + Map&Guide using the format. +

Coordinates are stored in Mercator format. The + calculation between this and our internal format can result + in visible differences. Experience reports are + welcome.

Options:

+ index - If more then one route are present in + source data, with this option you can determine, which of this + should used for the output. The range is 1 to number routes in + input. If you don't use this, only the first route will be + converted. +

+ name - Not every input format has a real name + for routes in their data. So you can give the route a nice + name.

+ radius - Overwrites the default value of + 6371000.0 meters for the earth radius. My be this can help to + reduce differences.

ExampleÂ 3.1.Â An example with all options

gpsbabel -r \
+	 -i gpx -f in.gpx
+         -o bcr,index=1,name="From A to B",radius=6371012 \
+	 -F a_to_b.bcr
+

CETUS

Cetus, for Palm OS

Cetus GPS www.cetusgps.dk is a + program for Palm/OS. Working with Ron Parker and Kjeld + Jensen, we can now read and write files for that + program.

compegps

CompeGPS

Suppport for CompeGPS data files.

These data files are "character" separated text files like + the pcx format. "Character" means special data lines can + have their own separator.

coastexp

CoastalExplorer (tm)

This is the format used by CoastalExplorer + (tm). The format is XML with items uniquely identified + by Windows-style UUIDs. http://www.rosepointnav.com +

CoPilot

CoPilot Flight Planner for Palm OS

This code is mostly intended to convert CoPilot Flight + Planner for Palmd/OS atabases into other formats. You + probably should not use this to write CoPilot databases, + although the code is there, because GPSBabel doesn't convert + magnetic declination values.

Questions, bug + reports, etc, to ptomblin at xcski.com

+ http://xcski.com/~ptomblin/CoPilot/ + and http://navaid.com/CoPilot +

COTO

cotoGPS, a Palm GPS program

Format for cotoGPS, a Palm GPS + program. It can read both track and marker (waypoint) + files. It is currently unable to write track files, so only + marker files can be written. The marker categories are + written to and read from the icon description. The 'Not + Assigned' category leaves the icon description empty on + read. Currently geocache info is ignored.

+ Options:

+ zerocat (output) - Name for the Palm + 'Not Assigned' category. Defaults to 'Not Assigned'. +

There is also a debugging option called 'internals' + which takes a XCSV delimiter value. It writes some internal + values (distance, arc, x and y) of the cotoGPS track format + to the notes field. URL: core.de/~coto + Contributed by Tobias Minich. +

CST

CarteSurTable - French shareware

With this format we can read CarteSurTable data files. + CarteSurTable is a shareware program widely used in France. + The data inside have to be seen as a mixture of a waypoints + list, one route and several tracks. phgiraud.free.fr +

CSV

Comma Separated Variable, for Delorme + S&A Deluxe

There are a billion variants of Comma Separated Value + data. This is the one that makes Delorme S&A Deluxe 9 + happy. It's also a very simple program and useful for many + other programs like spreadsheets.

CSV is also the correct format for Lowrance MapCreate, + their commercial mapping program, or GDM6 (their free + waypoint manager) for iFinder which is available at lowrance.com +

custom

Plain CSV

This is a "kitchen sink" CSV format. No known program + will read it, but it's handy for simply converting an + arbitrary file to text so it can be pulled into a spreadsheet + or manipulated with text processing tools.

DNA

Nivitrak DNA marker format

Navitrak DNA marker format - Another CSV format file. + This is the format that is compatible with the DNA Desktop + import/export command. Reading the binary Markers.jwp format + directly off the data card is not supported yet. Contributed + by Tim Zickus.

EasyGPS

EasyGPS binary format

This is the binary file format used by EasyGPS. This + format is seemingly being phased out in favor of GPX in newer + versions of EasyGPS, but this allows conversions to and from + the old binary .loc format. +

+ http://www.easygps.com/ +

Information about and sketchy code to implement this + file format were provided by Eric Cloninger. +

Fugawi

Fugawi CSV format

This was a requested CSV format, *not* the proprietary + binary format used by Fugawi. Like any other CSV format, + GPSBabel cannot read tracks in this format, but converting a + track into it and then importing as track in Fugawi + works.

It is known to work with Fugawi V3.1.4.635. When + importing/exporting waypoints, one has to specify the order + of fields as follows (names of fields may depend on the + language used by Fugawi):

- Name

- Comment

- Description

- Latidude

- Longitude

- Altitude (metres)

- Date (yyyymmdd/yymmdd)

- Time of day (hhmmss)

When importing tracks, use "[ignore]" instead of + "Name", "Comment" and "Description".

+ http://www.fugawi.com/ +

GARMIN

Garmin waypoint format

Waypoint serial upload and download works reliably + under both POSIX and Windows. I originally tested it with a + Vista, a V, and a base eTrex, all graciously provided on loan + by Joe Armstrong, but it's now regularly exercised on a 60CS + (USB and serial) and many other models. The communications + library used, jeeps, claims to support most models of Garmin + hardware. Be sure the GPS is set for "Garmin mode" in setup + and that nothing else (PDA hotsync programs, gpsd, getty, + pppd, etc.) is using the serial port. +

GPSBabel supports the USB Garmins under Windows and on + Linux and OS/X via libusb. It's reported successful with + VistaC, SummitC, 60C, 60CS, 76C, 76CS, 96C, and Quest. Some + users report success with StreetPilot 2610 and some do not, + but nobody's followed up with details on that. +

Currently, only a single USB unit at a time can be + supported. The device name to use on the command line is + "usb:" Thus, to read the waypoints from a Garmin USB unit and + write them to a GPX file: +

gpsbabel -i garmin -f usb: -o gpx -F blah.gpx

When reporting problems with Garmin, be sure to + include the full unit model, firmware version, and be + prepared to offer debugging dumps by adding "-D9" to the + command line, like: +

 gpsbabel -D9 -i garmin -f usb: -o gpx -F blah.gpx

Custom icons are supported on units that support that. + Neither GPSBabel nor your firmware know what is associated + with any given slot number. They don't know that the picture + you placed in the first slot is a happy face, they only know + they're in the lowest numbered slot. GPSBabel names the them + consistently with Mapsource, so they are named 'Custom 0' + through 'Custom 23'. +

Gcdb

GeocachingDB format

This is the GeocachingDB by DougsBrat. It works with + v2 and v3 of this program. See vip.hyperusa.com +

GDB

Garmin GPS Database (as in MapSource) + format

Support for the "Garmin GPS Database" format used by + default in MapSource versions since release 6.0. By default + we create gdb's of version 2. Version 2 is used in Mapsource + 6.3 and 6.5. +

Garmin GPS database is an undocumented file + format. The basic info for this module comes from the + existing MapSource conversion code. +

Additional options:

+ ver - set the data format version of the output file (currently +1 or 2); 2 is our default.

+ via - Drop hidden route points (means +calculated stuff)

+ cat - default category on output (1..16)

GEO

geocaching.com .loc file format

geocaching.com spits up geocaching.loc files that are + XML-ish but not quite GPX. Becuase it's so close to GPX, this + format is very well supported.

Geocaching DB

GeocachingDB PDA format

This is a PDA file format. It was tested against + version 2 of GeocachingDB and a development snapshot of + version 3. Information on the file format came from Dougs + Brat and Ron Parker. A particularly handy way to use + GPSBabel on these files is to use GPSBabel to read a GPX file + with Groundspeak (geocaching.com) extensions and let it write + you a GeocachingDB file that contains the cache names, + difficulty, terrain, and such.

+ vip.hyperusa.com +

GEOnet

GEOnet Names Server country file format (input)

Input support for the GEOnet Names Server (GNS) country + file structure. Export to this format is not possible, as + this format has too many fields that we never get populated + by any other format.

geoniche

Geoniche - Palm format for off-road users

Geoniche is a Palm/OS application oriented for the + off-road user. This module was contributed by Rick + Richardson. See nwlink.com +

glogbook

Garmin logbook format for Forerunner and ForeTrex

This is the XML format used by the Garmin Logbook + product that ships with Forerunner and Foretrex. http://www.garmin.com +

GOOGLE

Google maps routes

This format is designed to read the XML emitted when + you tack "&output=js" onto the end of a Google Maps + route URL (use the "link to this page" option to get a usable + URL.) This allows you to plan a route using Google Maps, + then download it and use it in your own mapping program or + GPS receiver. If you use a Unix-compatible operating system, + this shell script might be useful: +

        
+#!/bin/sh
+FROM="233 S. Upper Wacker Dr, Chicago, IL"
+TO="1060 W. Addison St, Chicago, IL"
+wget -O - "http://maps.google.com/maps?q=$FROM to $TO&amp;output=js" \
+           2&gt;/dev/null &gt;google_map.js
+

 gpsbabel -i google -f google_map.js -o gpx -F google_map.gpx
+

Note that Internet Explorer has been observed to + damage the XHTML beyond recognition so use a better browser + to save the pages such as Firefox or Mozilla. +

GpilotS

Palm OS format for GPilots

This is a Palm/OS file format for GPilotS. It was + tested against version 6.2. +

+ http://www.cru.fr/perso/cc/GPilotS/ +

Neither tracks nor routes are supported at this + time.

gpl

Delorme gpl format

This is the 'gpl' format as used in Delorme mapping + products. It is a track format and contains little more than + the tracklog of a GPS that was attached while driving. frontiernet.net +

GPSDRIVE

GpsDrive way.txt file format.

GpsDrive way.txt file format. A space seperated format + file. Tested against GpsDrive v 1.30 found at kraftvoll.at. + Contributed by Alan Curry.

GPSDRIVETRACK

GpsDrive saved track format

Format used by GpsDrive to save tracks. Like GPSDRIVE a + space seperated format file. See above for a link to + GpsDrive. Contributed by Tobias Minich.

GPSMAN

GPS Manager format (WGS84, DDD)

GPS Manager can read and write formats that this + converter doesn't understand. The default formats (WGS84, + DDD) work reliably.

GPSPILOT

GPSPILOT file format

The file format for GPSPILOT gpspilot.com was + provided by Ron Parker. The output from this module has been + tested with GPSPilot Tracker v5.05sx, but it is based on + reverse-engineering so it may not work with all versions of + all GPSPilot products. It had read-only support for Airport, + Navaid, City and Landmark files but will read and write Point + files.

GPSUTIL

GPSUtil file format

GPSUtil has a simple file format of this program that + runs on POSIX- compliant OSes like UNIX and Linux. Reads and + writes of this format are reliable. (I've also contributed + to this program.) It's available at cs.uakron.edu.

GPX

EasyGPS, ExpertGPS etc format.

This is the most capable and expressive of all the file + formats supplied. It is described at topografix.com + and is supported by EasyGPS, ExpertGPS, and many other + programs described at topografix.com +

Hiketech

Mac OS HikeTech formats. TopoDraw, Link2GPS & GPSWrite

This is the .gps format used by the Mac OS X + applications written by HikeTech. These include TopoDraw, + Link2GPS, and GPSWrite. More information about these products + can be found at hiketech.com +

HOLUX

Holux format (Holuxgm-100)

The Holuxgm-100 (e-fox) gps receiver uses standard + compact flash cards. File formats were provided by + Holux-Taiwan holux.com to the + author. The code was tested against version 2.27E1; other + versions and receivers may work but have not been explictly + tested. Anyone with information on other Holux receivers is + encouraged to contact jochen@bauerbahn.net. +

When copying the .wpo file to a flash card, the file + must be named tempwprt.wpo as the receiver will + ignore all other files. +

Comparing the waypoints of a .wpo files against other + formats like .gpx you may notice a small difference in the + latitude and longitude values. The reason is the low + resolution of the coordinates in the wpo file format. In a + .wpo file the reolution is 1/10"; in gpx for example it is + 1/100". A a practical matter, this loss is only about 1.7 + meters (5 feet). +

The generated waypoint failes can also be used by + MapShow version 1.14. This program is free of charge from + the Holux web site. +

This format was contributed by Jochen Becker. +

hsandv

HSA Systems Endeavour Navigator format

HSA Systems Endeavour Navigator format - will import + both the old version 4.x binary files, and the newer XML + based ones. Only writes the new XML (5.0 and above) + format. (use the .exp extension)

HTML

HTML format

HTML output generates a single HTML file of all of the + waypoints in the input file. It supports a number of + Geocaching GPX extensions, as well as filters out potentially + harmful HTML from the input file while maintaining almost all + of the source HTML formatting. Use the 'stylesheet' option + to specify a CSS stylesheet to be used with the resulting + HTML file. Use the 'encrypt' option to encrypt hints from + Groundspeak GPX files. Use the 'logs' option to include + Groundspeak cache logs. +

The following command line reads a GPX file with + Groundspeak extensions and writes an HTML file with encrypted + hints that is rendered using a custom stylesheet: +

gpsbabel -i gpx -f 12345.gpx \
+     -o html,stylesheet=green.css,encrypt -F 12345.html
+

IGC

FAI/IGC Data file format

FAI/IGC Data File -- Used by the international gliding + community to record gliding flights. IGC files can be + converted to and from tracks representing recorded flights, + and routes representing task declarations in other + formats.

IGNRando

IGN Rando track file format

Input and output support for IGN Rando track files. + IGN Rando is a program mainly used in France for Topo maps. + The files are XML based and are "windows-1252" encoded. + Trackpoints come without timestamp.

+ + Options: +

+ index - Use track + number <index> from input data for output. The + range is 1 to number of tracks in input. +

KML

Keyhole Markup Language format.

KML, the Keyhole Markup Language, is used by Keyhole and + Google Earth. (Google Earth uses GPSBabel internally for + receiver communications and several file format imports and + exports. There are features in this file format that we + don't support such as camera views, but waypoints, tracks, and + routes work well.

Additional options:

+ lines=n (default n=1) Draws lines + between points in tracks and routes when n is + non-zero.

+ points=n (default n=1) Draws + placemarks for tracks and routes when n is non-zero.

+ line_width=n (default n=6) Width of + drawn lines, in pixels.

+ line_color=n (default=65eeee17) Line + colour specified in hex AABBGGRR.

+ floating=n (default n=0) Altitudes + are not clamped to ground when n is non-zero. This option is + more useful to pilots than to hikers.

LowranceUSR

Lowrance iFinder .USR format

The Lowrance iFinder GPS series has the unique + capability to output its data to an MMC card. The data is + saved to the card as a .USR file and can be read by your + computer using a card reader. Waypoints, routes, tracks are + supported. By default, Event marker icons are converted to + waypoints. Symbols tend to get lost in the + translation.

Additional options: ignoreicons - don't convert icons + to waypoints merge - (USR output) merge all tracks into a + single track with segments break - (USR input) break track + segments into separate tracks

mag_pdb

Palm OS for Map&Guide format

With this format we support the + Palm/OS export for Map&Guide based products like + "PowerRoute", "Motorrad-Routenplaner" and (maybe) other + software. The exported files can contain maps and/or route + descriptions. The reader for this format has been tested with + PowerRoute 5+6, Motorrad-Routenplaner 2002(-2006).

MAGELLAN

Magellan format

Waypoint serial upload and download works reliably to + the 315, 330, Meridian, and SportTrak family. I expect it to + work on any modern Magellan unit.

As of 08/30/02, GPSBabel can also read and write the + files that can be stuck on the SD memory cards with the + Meridian models. Simply specify a file instead of a serial + port.

Communication errors are handled robustly and + verification of data is enabled.

Additional suboptions: baud: + may be 1200, 2400, 4800, 9600, 19200, but must match + receiver.

MAGELLANX

Magellan Explorist format

The SD card format used by the Magellan Explorist 400, + 500, and 600. It's identical to the Magellan SD format used + by Meridian, but allows longer waypoint names.

You should name any file created with this format with + a ".upt" extension so the firmware can read it.

MAGGEO

Magellan SD card format

The SD card format used by the Magellan Explorist 400, + 500, and 600 to describe geocaches. Notice what while the + format can hold an infinite number of geocaches, the unit + will read and silently discard all but 200 geocache POIs at a + time.

You should name any file created with this format with + a ".gs" extension so the firmware can read it. +

MAGNAV

Magellan Nav Companion format

Magellan NAV Companion for Palm/OS is not really + designed for this sort of use, but its file format is + supported and with a little bit of patience you can both read + and write NAV Companion waypoints. Please read README.magnav + for further tips on getting waypoints in and out of NAV + Companion. This conversion is based on partially incomplete + reverse-engineering of the record format, so it may not work + with all versions of NAV Companion. It has been tested with + version 2.10 and 3.20.

mapconverter

Mapconverter format from Mapopolis

Mapconverter is a format this is read by + Mapopolis.com's mapconverter application. Full details of + it's usage are available in the file + README.mapconverter.

MAPSEND

Magellan Mapsend format

Magellan was smart enough to document their file format + to make creating software like this possible.

MAPSOURCE

Garmin Mapsource format

Garmin Mapsource format appears compatible with the + various members of that product family. Icon mapping is + attempted between different MapSource versions. Altitude is + supported, but proximity and depth are not. Naming files + *.mps will allow file->open in Mapsource to find the files + more easily. Versions 3, 4 and 5 of the Mapsource data + format are handled automatically on input and by default the + output is version 5. (Until 3/2004, it was version 3, but + since Mapsource updates are free, the convenience of having + modern icon sets outweighs the backward compatibility + concern. Users of other versions can either upgrade or + specify the switches to get get output in a compatible + format.) Waypoints, routes and tracklogs are all handled, + but maps sets are ignored. +

Information on the Garmin Mapsource format was + provided by Ian Cowley and Mark Bradley. The code was + implemented by Robert Lipe and Mark Bradley.

Additional options:

+ snlen + - set the length of generated shortnames

+ mpsverout - set the data format version of + the output file (3,4 or 5)

+ mpsmergeout - if the output file already + exists, then the output is merged with it. This allows MapSource + sections not being handled to remain intact (e.g. map sets)

MSroute

Microsoft Autoroute 2002 format

Input support for Microsoft + AutoRoute 2002 .axe files. These files contains only + routes. We can extract the coordinates and the names of the + points within route. An export to this format will not be + supported. +

MXF

Maptech Exchange format.

Maptech Exchange Format - Another + CSV format file. This format complies with (at least) + Maptech Terrain Navigator, Terrain Professional, Take a Hike, + and ExpertGPS import/export MFX. Contributed by Alex + Mottram.

navicache

Nivicache.com's XML format

This is the XML format that's + used by Navicache.com for their geocaching data. There are a + number of fields in it that are marked "required" but are + Navicache-specific, so GPSBabel can not write these files, + but we can still read them. navicache.com +

Netstumbler

NetStumbler CSV summary file format

NetStumbler 0.4 Summary + File -- Another CSV format file. The default behavior when + creating waypoints is to use the SSID for the short name, and + information about the access point for the description. When + the SSID is not unique, is not available, or consists of + whitespace, a shortname is synthesized. The snmac option + uses the MAC address for the shortname, and includes the + unmodified SSID in the description. Different icons are + assigned to encrypted, non-encrypted, stealth, and + non-stealth access points; these may be changed with options. + Import only. +

Additional options:

+ nsneicon - Name of icon used for non-stealth + non-encrypted access points

+ seicon - Name of icon used for stealth + encrypted access points

+ sneicon - Name of icon used for stealth + non-encrypted access points

+ snmac - Always use the MAC address as the + shortname.

NIMA

National Imagery and Mapping agency format

This is a CSV format from the National Imagery and + Mapping Agency.

nmea

NMEA0183 log and waypoint format

This format is the file representation of the NMEA0183 + log and waypoint format. Representative programs + include:

+ genimap.fi +

+ homepages.tig.com.au +

+ gpstm.com +

+ gpsmaster.nl +

+ silcom.com/~rwhately +

+ visualgps.net +

+ gpsu.co.uk +

+ kolumbus.fi +

+ commlinkx.com +

nmn4

Navigon Mobile Navigator route (.rte) files.

Support for Navigon Mobile Navigator route (.rte) + files. This is a very simple text format that only requires + coordinates, but has fields for many other things. We only + write coordinates as fields like 'city' and 'street' cannot + typically be populated from other formats. + + www.navigon.com +

OPENOFFICE

Tab seperated file format - numerical processing

Tab seperated export-all (except geocaching data) file + format. Intended to serve as source for number-processing + applications like OpenOffice, Ploticus and others. Tab was + chosen as delimiter because it is a) supported by both + OpenOffice and Ploticus and b) is not ',', so you can use + sed -i "s/./,/g" + <x>.csv' to adapt it to locales where ',' is + used as decimal seperator. Contributed by Tobias + Minich.

OZI

OziExplorer Waypoint Format

OziExplorer Waypoint Format - Another CSV format file. + Tested against OziExplorer v 3.90.3a / Shareware. + Contributed by Alex Mottram

PALMDOC

PalmDoc output format

PalmDoc output is similar to Text output, except that + it generates a Palm Database (PDB) file suitable for use with + programs like CSpotRun, TealDoc, AportisDoc, Palm Reader, and + others. The resulting file also contains bookmarks to make + it easy to jump to a particular waypoint. To suppress the + dashed lines between waypoints, use the 'nosep' option. To + specify a name for the document, use the 'dbname' option. + Use the 'encrypt' option to encrypt hints from Groundspeak + GPX files. Use the 'logs' option to include Groundspeak + cache logs. If you would like the generated bookmarks to + start with the short name for the waypoint, specify the + 'bookmarks_short' option. This is particularly useful when + used in combination with the 'sort' filter. +

The following command line reads a GPX file with + Groundspeak extensions and writes a Palm document with + encrypted hints and logs: +

gpsbabel -i gpx -f 12345.gpx \
+       -o "palmdoc,dbname=Unfound Geocaches,encrypt,logs" \
+       -F 12345.pdb
+

PathAway

PathAway for Palm file format

PathAway is a Palm software designed for handling + "most" GPS devices (including BlueTooth). In this time (I + mean 2005) a free tool to convert this database is located on + the homepage of PathAway (www.pathaway.com). But I've read + there ... for windows and the output formats are also very + limited. +

PCX

Garmin PCX format

Garmin documents only PCX5, an older format limited to + the lame NMEA six-character waypoint names that's treated as + a second-class citizien in current versions of MapSource. In + Mapsource, use file->import to read these files. If you + name the files *.wpt, Mapsource will find them easier. +

In general, you should prefer the "mapsource" file + format to this one. +

PsiTrex

KuData's Psion PDA format

This is a text format created by KuDaTa's PsiTrex + program for the Psion PDAs. The format can't be readily + handled by XCSV, so this format is handled explicitly. + Waypoints, routes and tracks are all handled, with icon names + used corresponding to verison 1.13 of PsiTrex. This module + was contributed to GPSBabel by Mark Bradley.

PSP

Microsoft PocketStrees 2002 pushpin + format

Microsoft's PocketStreets 2002 + Pushpin (.PSP) format is not yet completely documented. THE + .PSP MODULE DOES NOT WORK WITH MS STREETS & TRIPS 2002 + .EST FILES. To create .PSP files from Streets & Trips + 2002, you will need to have PocketStreets support installed. +

Please note that MS Streets & Trips only *EXPORTS* + .PSP files. It does not import them. MS Streets & Trips + 2002 only imports CSV files. To use .PSP files, simply copy + them over to the same folder on the mobile device as the map + (.MPS), and open PocketStreets. It should also be noted that + in the case a pushpin is outside of the exported map area, + the pin will be "grayed-out" and unused in PocketStreets. + This is a good thing as it allows us to create one big .PSP + file that covers multiple .MPS files. Unfortunately, you + need one .PSP file for every .MPS file. :(

QUOVADIS

QuoVadis for Palm OS format

QuoVadis for Palm OS marcosoft.com is a + program for Palm/OS. Working with record definitions provided + by MarcoSoft and further experimentation by Bruce Thompson + and "Fuzzy" from the Geocaching Forums to nail down the + format precisely.

Should work fine for import and export.

One thing of note, QuoVadis stores all waypoints in a + single Palm Database without using categories. This means + that it may be difficult to keep personal waypoints separate + from generated waypoints. What Bruce recommends is taking the + QuoVadisMarkerDB.PDB file synced down from your Palm Powered + device and extract the waypoints you personally set to a GPX + file. Then using GPSBabel's joining capabilities generate a + new PDB file from the personal file and the other waypoint + files of interest.

Currently the selection of icons to display and the + scale at which to display them is hardcoded. Also there is no + support for notes associated with waypoints. This will be + addressed in a future revision.

s_and_t

Microsoft Streets and Trips import format

This is a format for importing into Microsoft Streets + and Trips. It's been exercised on versions 2003, 2004, and + 2005. Detailed instructions on how to use it, including + preserving hyperlinks, are at gpsbabel.org +

saplus

Street Atlas USA 2004 Plus format

This format is for Street Atlas USA 2004 Plus. +

For geocachers importing data from a tool like GSAK or + Spinner, import the file twice in XData. One will create a + file with the Cache description as a hyperlink on the flag. + This can clutter up the screen and when you try to zoom in, + it causes problems. So the second one will only have a flag. + Thus you can turn off and on which one you want to view. The + first time you import the file, in the assign field types, + check the circle above Full Name and then next. The second + time you import the file do not check any circle and in the + second to last column, change URL to none and then click + next. Use the same name you used the first time but add -Flag + to it. +

saroute

Delorme (anr, rte, rtd files)

This is a catch-all used by many Delorme mapping + products and reads the anr, rte, and rtd formats as either + tracks or routes.

The 'turns_only' option causes GPSBabel to read only + the waypoints associated with named turns. This should + create a list of waypoints that correspond to the itinerary + from Street Atlas.

The 'turns_important' option only makes sense in + conjunction with the 'simplify' filter. It ensures that the + route simplification process will remove the points + corresponding to turns only after it has removed all other + route points. +

The 'split' option causes GPSBabel to create separate + routes for each street, creating a new route at each turn + point. For obvious reasons, 'split' cannot be used at the + same time as the 'turns_only' or 'turns_important' + options.

The 'controls' option lets you read the control points + (start, end, vias, and stops) for your route as well as the + route itself. The default for this option is 'none', which + won't read the control points. You may also specify + 'waypoints', which reads the control points as waypoints, or + 'route', which creates an extra route named 'control points' + containing just the control points in order. Note that if + your goal is to create an arc or other CSV file, you should + use 'none' (or not use this option, which is the same + thing.)

All options only apply to route files from newer (anr) + versions of DeLorme software; older versions didn't store the + turn information with the route. +

STMwpp

Suunto Track Manager WaypointPlus format.

Support for Suunto Track Manager (STM) WaypointPlus + format.. Simple structure with coordinates and + timestamp. Route points (waypoints) have additionaly + shortname. The files can only contain one route or one + track. www.suunto.fi +

+ + Options: +

+ index - Use route/track number <index> from input data for output. +

tabsep

Unix tab seperated file format

Dumps all fields in a traditional + Unix tab separated style.

TEF

TourExchangeFormat. for Map&Guide

TEF, internal called "TourExchangeFormat", is a XML + based export format, used by Map&Guide + "Motorrad-Routenplaner 2005/06". Another posibility to + exchange data with this are the .bcr files, which are + supported by GPSbabel in both directions (see BCR). +

Via XML this software can only export routing data. So + we don't support writing. With the option "routevia" you can + eliminate calculated route points from tef source + file.

 gpsbabel -r -i tef,routevia -f in.xml -o gpx -F out.gpx

TEXT

Plain text, for people

This is a simple human readable version of the data + file, handy for listings of any type of waypoint files. Use + the 'nosep' option to suppress the lines of dashes between + entries. Use the 'encrypt' option to encrypt hints from + Groundspeak GPX files. Use the 'logs' option to include + Groundspeak cache logs. +

The following command line reads a GPX file with + Groundspeak extensions and writes a text file with encrypted + hints: +

gpsbabel -i gpx -f 12345.gpx -o text,encrypt -F 12345.txt
+

TIGER

US Census Bureau mapping format

The U.S. Census Bureau provides online mapping + facilities. This format is described at: tiger.census.gov. + Do notice that this format is not the actual Tiger line + mapping records, but rather the interface to their online + mapping program.

TMPRO

TopoMapPro places file

TopoMapPro Places File. Reads and writes places files + for use in TopoMapPro topomappro.com). As + this file type can store links other than web links, anything + that is not a http url will be discarded. Note that this + does not do datum conversions, so if your input file does not + have WGS84/NZGD2000 data, your output file won't either. + Colour of waypoint icons defaults to red.

TomTom

TomTom .ov2 POI files

This format can read and write TomTom .ov2 (POI) + files, as used by the TomTom GO and TomTom Navigator. It has + been tested with an original TomTom GO running version 5.00 + of the TomTom software. There may be some records that + confuse the input module - if you have an example of such a + record "in the wild", and you aren't restricted from sharing + it, we encourage you to post to the gpsbabel-misc mailing + list to contact a developer.

Note that in addition to the .ov2 file, you will + need a .bmp file for the icon. It should be 22x22 and + 16 colors, and have the same name (not including the + extension) as the .ov2 file. +

TPG

National Geographic Topo Waypoint format.

National Geographic Topo! Waypoint Format. This filter + reads and writes .TPG files created by various editions of NG + Topo! This filter will *not* work with the newer combined + .TPO files. Contributed by Alex Mottram.

The option 'datum="datum name"' can be used to override + the default of NAD27 ("N. America 1927 mean") which is + correct for the continental U.S. Points in Hawaii should use + "Old Hawaiian_mean"

Contributed by Alex Mottram.

vCARD

vCard format for Apple iPod etc.

The vCard output is intended to be in a format that + enables waypoints to be viewed with an Apple iPod. This is + achieved by mapping waypoint fields into vCard fields that + can be displayed as 'Contacts' on the iPod. With the iPod + mounted as a hard disk (see your iPod manual for + instructions), the resulting VCF file should be moved into + the iPod 'Contacts' folder. As an alternative, Mac OS X users + may prefer to drag the VCF file into their address book and + synchronize with the iPod using iSync. By default hints are + unencrypted; use the 'encrypt' option to encrypt the + hints.

VitoSMT

Vito Navigator II format

Vito Navigator II is a Pocket PC GPS application. This + format reads a Vito Navigator II .SMT track file and can work + in either waypoint or track mode. The speed, heading and + Dilution of Position data is written in the notes + field.

Support for writing .SMT tracks is very experimental + and may crash VitoNavigator II on the Pocket PC.

XCSV

For user supplied style files

XCSV is an open-ended "Whatever Separated Values" + parser / writer designed to work with user-supplied "style" + files. It should handle at least a few thousand of the + billion CSV variants available. By itself, it doesn't comply + to any format, however *most* CSV variants can be described + as a "style" and fine-tuned by the end user. For more + information on it's use, please see README.style in the + style/ sub-directory of GPSBabel. For an example of using + the XCSV module within your C program, look at the ozi.c, mxf.c, and xmapwpt.c sources in the GPSBabel + directory. This module was contributed to GPSBabel by Alex + Mottram.

Additional Options:

+ style - **REQUIRED** Path to XCSV style file.

+ snlen - Maximum length of synthesized shortnames.

+ snwhite - Switch defining whether or not to allow whitespace + in synthesized shortnames. + (0 = NO WHITESPACE, 1 = WHITESPACE OK).

+ snupper - Switch defining whether or not to + force uppercase in shortnames. + (0 = LEAVE AS IS, 1 = UPPERCASE ALL). + NOTE: sn* options require use of the '-s' command line option.

ExampleÂ 3.2.Â Example Usage:

 gpsbabel -i xcsv,style=foo.style -f foo \
+  -o xcsv,style=bar.style \
+  -F bar

 gpsbabel -s -i gpx -f foo.gpx \
+  -o xcsv,style=my.style,snlen=8 
+  -F bar

XMap

Delorme TopoUSA/XMap Conduit + format

Delorme TopoUSA/XMap Conduit is one + of the billion CSV variants mentioned above. It's just like + S&A with the addition of a completely pointless line at + the beginning and end of the file. This is the format used + to hot-sync to XMap from withing TopoUSA. Done with help of + Dan Edwards.

XMapWpt

Delorme XMapHandHeld street Atlas format.

Delorme XMapHandHeld Street Atlas USA is another of the + billion CSV variants. This is the format used by XmapHH SA + USA on (at least) PocketPC O/S. Please see README.xmapwpt + for more information on it's intricacies. This XMap is not + to be confused with the XMap mentioned above. Contributed to + GPSBabel by Alex Mottram.

ChapterÂ 4.Â DATA FILTERS

Table of Contents

POSITION
RADIUS
DUPLICATE
DISTANCE FROM A ROUTE (ARC) ARC
POLYGON
SIMPLIFY
REVERSE
SORT
STACK
TRACK
START / STOP
SPLIT
MERGE
DISCARD

GPSBabel supports data filtering. Data filters are + invoked from the command line via the '-x' option. It should be + noted that data filters are invoked in the internal pipeline at + the point that corresponds to their position on the + command. This implies that specifying a filter before reading + any data ('-x <filter> -f <file>'), despite being + legal, will not have any effect. The advantage is that filters + can be used intermittently between several variations of input + and output functions. It should also be noted that filtering + data from different input types can sometimes produce + undesirable results due to differences in the native data + formats. +

Beware that most filters only apply to a certain kind of + data. This is usually indicated below by referring to points, + tracks or routes in the first sentence which describes each + filter or in the table at gpsbabel.org + . +

POSITION

The position filter is designed to remove points based + on their proximity to each other. Distances can be passed on + the command line by passing the distance=XXX option to the + filter. Distance options may be expressed in feet + (distance=3f) or + meters (distance=1m). + The default is zero feet, essentially a duplicate position. +

ExampleÂ 4.1.Â An example

gpsbabel -i geo -f 1.loc -f 2.loc -x position,distance=1f  	\
+         -o mapsend -F 3.wpt

would remove multiple points that are within 1 foot of + each other, leaving just one.

You can also specify the "all" option, which would + remove all of the points rather than leaving one.

RADIUS

The radius filter is designed to include points based + on their proximity to a central point. Distances and the + central point are declared on the command line by passing the + distance=X.XX, + lat=X.XX, and + lon=X.XX options to + the filter. Distance options may be expressed in miles + (distance=3M) or + kilometers (distance=3K). The default is + zero miles. Additionally, the exclude option may be + specified to reverse the effect of the filter, so that points + further from the center are kept and closer points are + discarded.

ExampleÂ 4.2.Â For example:

gpsbabel -i geo -f 1.loc \
+   -x radius,distance=1.5M,lat=30.0,lon=-90.0   \	         
+   -o mapsend 
+   -F 2.wpt

would include only points within 1.5 miles of N30.000 + W90.000 +

DUPLICATE

The duplicate filter is designed to remove duplicate + points based on their shortname (traditionally a waypoint's + name on the GPS receiver), and/or their location (to a + precision of 6 decimals). This filter supports two options + that specify how duplicates will be recognized, "shortname" and "location". Generally, at least + one of these options is REQUIRED.

ExampleÂ 4.3.Â For example:

 gpsbabel -i gpx -f 1.gpx -f 2.gpx -x duplicate,location,shortname  \	         -o gpx -F merged_with_no_dupes.gpx

would remove points that have duplicate shortnames + *AND* duplicate locations. The result would be a GPX file + that more than likely contains only unique points and point + data.

The duplicate filter can also take an "all" option. + If you specify that option, all instances of a duplicated + waypoint will be removed, not just the second and subsequent + instances. If your input file contains waypoints A, B, B, + and C, the output file will contain waypoints A, B, and C + without the "all" option, or just A and C with the "all" + option. This option can be useful as an "ignore list" in + some circumstances. +

Finally, the duplicate filter takes a + "correct" option. If you specify that + option, the latitude and longitude frmo later duplicates will + replace the latitude and longitude in earlier waypoints. You + can use this to apply a list of "waypoint corrections" to a larger + file, while keeping all of the other details from the larger + file.

DISTANCE FROM A ROUTE (ARC) ARC

The arc filter is designed to include points based on + their proximity to an arc, which is a series of connected + line segments similar to a route or a track but without any + associated data other than the coordinates. +

The arc is defined in a file whose name must be + provided with the file=XXXX option to the filter. + That file contains pairs of coordinates for the vertices of + the arc, one coordinate pair per line. Comments may be + included by preceding them with a '#' character. An arc file + looks something like this sample: +

	  
+# Lima Road/SR3 north of Fort Wayne, Indiana 	  
+41.150064468    -85.166207433 	  
+41.150064468    -85.165371895 	  
+41.149034500    -85.165157318 	  
+41.147832870    -85.164771080 	  
+41.146631241    -85.164384842 	  
+41.144270897    -85.163655281 	  
+41.141953468    -85.162882805

An arc file may optionally contain gaps in the arc. You can + specify such a gap by inserting a line containing "#break" + either on a line by itself or after the coordinates of the + starting point of the new arc segment. +

In addition to the file containing the arc, you should + also specify the maximum distance from the arc that will be + accepted; that distance is declared on the command line with + the distance=X.XX + option to the filter. Distance options may be expressed in + miles (distance=3M) or + kilometers (distance=3K). The default is + zero miles. You may also specify the exclude option, which + causes GPSBabel to only include points that are further than + the specified distance from the arc. +

For example, assuming the arc above is in a file called lima_rd.txt:

	gpsbabel -i geo -f 1.loc 
+   -x arc,file=lima_rd.txt,distance=1  	\
+   -o mapsend 
+    -F 2.wpt

would include only points within one mile of the + section of Lima Road covered by the arc.

POLYGON

The polygon filter includes points if they are inside + of a polygon. A polygon file looks like an arc file, except + that the arc it describes must be a closed cycle. That is, + for a simple polygon, the first and last points must be the + same. Here's a square: +

+          # A square (not really) polygon
+          41.0000       -85.0000
+          41.0000       -86.0000
+          42.0000       -86.0000
+          42.0000       -85.0000
+          41.0000       -85.0000
+

Polygons may include islands and holes. To specify an + island or a hole, just append it to the main polygon. +

As with the arc filter, you specify a polygon by + specifying the name of the polygon that contains it, using + the file option. You can also specify the exclude option, + which reverses the operation of the filter so that it only + includes points that are NOT in the polygon. +

Note that this filter currently will not work properly + if your polygon contains one or both poles or if it spans the + line of 180 degrees east or west longitude. +

For example, assume you have a polygon file that + defines the border of your county, called mycounty.txt. This + command line will give you only the points in your county: +

	gpsbabel -i geo -f 1.loc -x polygon,file=mycounty.txt  	  	 \
+-o mapsend -F 2.wpt

SIMPLIFY

The Simplify filter is used to simplify routes and + tracks for use with formats that limit the number of points + they can contain. The filter takes one required parameter, + which is the maximum number of points a route may contain. + It attempts to remove points from each route until the number + of points is at or below the given maximum, while also + attempting to preserve the shape of the original route as + much as possible.

The quality of the results will vary depending on the + density of points in the original route and the length of the + original route. +

For example, suppose you have a route from Street + Atlas 2003 that you wish to use with a Magellan GPS receiver + that only supports up to 50 points in a route: +

gpsbabel -r -i saroute -f RoadTrip.anr \
+   -x simplify,count=50 \
+   -o magellan 
+    -F grocery.rte
+

REVERSE

The reverse filter is used to reverse tracks and routes. + It's mostly useful for those few formats where track/route + sequence matters and there isn't a way to reverse them using + the program itself.

The reversal is performed in the laziest way possible. + Timestamps are kept with the original waypoints so the + resulting track or route will have the interesting + characteristic that time runs backwards. This tends to make + Magellan Mapsend, in particular, do a wierd thing and place + each waypoint on a separate day. +

Additionally, if you're using this to reverse a route + that navigates, say, an exit ramp or a one way street, you + will be in for unpleasant ride. application cares about + timestamps +

SORT

This simple filter allows you to alphabetize waypoints + by shortname or by description. It has a special suboption + (gcid) to sort by geocaching.com waypoint ID's when the input + comes from a GPX file that has GC numbers in it. +

STACK

This filter is designed to solve advanced problems + that involve shuffling multiple lists of waypoints. It has + three distinct sets of suboptions:

PUSH

Pushes the current list of waypoints onto the stack. + If the 'copy' suboption is specified, a copy of the current + list is pushed onto the stack; otherwise, the current list is + cleared.

+-x stack,push
+-x stack,push,copy
+

POP

'Pops' the top list of waypoints off of the stack. + What is done with that list depends on the suboption + specified. If the 'append' suboption is specified, the top + list of waypoints from the stack is added to the end of the + current list of waypoints. If the 'discard' option is + specified, the top list of waypoints is removed from the + stack and discarded, leaving the current list of waypoints + unchanged. If the 'replace' option is specified, or if no + option is specified, the top list of waypoints from the stack + replaces the current list of waypoints; the previous contents + of the current list are discarded.

+                  
+-x stack,pop 
+-x stack,pop,discard
+-x stack,pop,append
+

SWAP

Swaps the current list of waypoints with a list from + the stack. If no further options are specified, the current + list is swapped with the top list on the stack. If the + 'depth' option is specified, it indicates which item on the + stack should be swapped.

+-x stack,swap        
+-x stack,swap,depth=2 
+

The stack can be used in conjunction with other + filters to implement a "union" or "logical or" functionality. + The basic idea is to use the stack to store copies of the + original list of waypoints, then use the 'swap' function to + replace each copy with a filtered list. Finally, append all + of the filtered lists to create one big list, which is then + output. The following example finds a list of all points + that are either inside county A or inside county B. Any + points that are inside both counties are duplicated (but the + duplicates can be removed with the DUPLICATE filter; see + above.) +

           
+gpsbabel -i gpx -f in.gpx \
+         -x stack,push,copy \
+         -x polygon,file=county_a.txt \    
+         -x stack,swap \
+         -x polygon,file=county_b.txt \
+         -x stack,pop,append \
+         -o gpx -F out.gpx
+

This example reads a large list of waypoints and + extracts the points within 20 miles of each of two cities, + writing the waypoint descriptions into two different PalmDoc + files and exporting all of the points to the GPS receiver: +

           
+gpsbabel -i gpx -f indiana.gpx \
+         -x stack,push,copy \
+         -x radius,lat=41.0765,lon=-85.1365,distance=20m \
+         -o palmdoc,dbname=Fort\ Wayne -F fortwayne.pdb \
+         -x stack,swap \
+         -x radius,lat=39.7733,lon=-86.1433,distance=20m \
+         -o palmdoc,dbname=Indianapolis -F indianapolis.pdb \
+         -x stack,pop,append \
+         -o magellan -F fwaind.wpt
+ 
+

TRACK

( !!! This filter always drops empty tracks !!! ) +

The track filter is a tool for manipulating track lists. The +following options are available:

TITLE

Gives the new track(s) a basic title. Basic means if + more than one track is created by filter the title will be + expanded with the date the new track. Special formats (see + UNIX date or strftime for details) are possible. +

+gpsbabel -t \ -i gpx -f in.gpx \ -x track,pack,split,title="ACTIVE
+LOG-%D" \ -o gpx -F out.gpx PACK
+

MOVE

Change the time of all trackpoints. This is useful if + your track has moved by one or more hours through a time zone + problem. The following example will shift your track to be + one hour later.

	    
+gpsbabel -t  -i gpx -f in.gpx  \
+    -x track,move=+1h,pack,title="ACTIVE LOG"  \
+    -o gpx -F out.gpx

START / STOP

Filter tracks against time borders. All points outside + this range will be dropped. The date-time paramters have to + be in form of YYYYMMDDHHMMSS; but you may specify only the + most significant portion represented in the the leftmost + fields. See the example, where the time is specified only + through the hour. If you only want to get a track mapped on + 20 july 2005 from 10 am to 6pm, you should use this:

+gpsbabel -t -i gpx -f in.gpx -x \
+      track,start=2005072010,stop=2005072018 \
+      -o gpx -F out.gpx

PACK

With this default option all tracks from input will be + packed into one track. If tracks overlaps in time, the filter + stops working. To pack all the tracks together into one + track and give it a name, use this:

	    
+gpsbabel -t  -i gpx -f in.gpx  	-x track,pack,title="ACTIVE LOG"  \
+		     -o gpx -F out.gpx

SPLIT

The input track will be split into several tracks + depending on date of track points. If there is more than one + track, use the pack option before before using this. To + split a single tracks into separate tracks for each day and + name them, use this: +

+gpsbabel -t -i gpx -f in.gpx -x \
+   track,split,title="ACTIVE LOG \
+    # %Y%m%d" -o gpx -F out.gpx

If the input has multiple tracks, pack them together before +splitting them back apart per day thusly:

     	    
+gpsbabel -t   -i gpx -f in.gpx  \
+     -x track,pack,split,title="ACTIVE LOG # %D"  	\
+     -o gpx -F out.gpx

Additionally you can add an interval to the split + option. With this the track will be split if the time + between two points is greater than this parameter. The + interval must be numeric and can be int days, hours, minutes + or seconds, expressed as one of the character "d", "h", "m", + or "s". If no trailing character is present, the units are + assumed to be in seconds. +

For example, to split a track based on an four hour + interval, use this:

            
+gpsbabel -t \ 
+     -i gpx -f in.gpx \ 
+     -x track,pack,split=4h,title="LOG # %c" \ 
+     -o gpx -F out.gpx
+

MERGE

Merge puts all track points into one single track and + sort them by time. Points with identical time stamp will be + dropped !!!

If you want to merge tracks from different devices but + from same trip, use this:

+gpsbabel -t \
+     -i gpx -f john.gpx \
+     -i gpx -f doe.gpx \
+     -x track,merge,title="COMBINED LOG" \
+     -o gpx -F john_doe.gpx
+

DISCARD

This filter 'fixes' gps data by discarding points with + a hdop and/or vdop over a set limit. If you give both the + hdop and a vdop options, by default points that exceed EITHER + are discarded (OR). This filter processes waypoints, tracks, + and routes. +

HDOP (float)

Points with a hdop exceeding the given value are + discarded. +

VDOP (float)

Points with a vdop exceeding the given value are + discarded.

HDOPANDVDOP

Only useful if both hdop and vdop are given. Now + logical AND is used, i.e. only points exceeding both given + values are discarded. +

Example:

 gpsbabel \ 
+	-i gpx -f in.gpx \
+	-x discard,hdop=10,vdop=20,hdopandvdop \ 
+	-o gpx -F out.gpx
+

Contributed by Tobias Minich.